But do we want the "build" in the URLs? Should we have (e.g.) https://ncas-cms.github.io/cf-plot/gopen.html, a la cf-python?

Good spot. Ideally not, but I like to separate out the built and source documentation into their own directories to keep them self-contained for dev and building and to do so I need to put the built content into a different directory. So unless I can find a way to point the root from https://ncas-cms.github.io/cf-plot/build/ to https://ncas-cms.github.io/cf-plot/, this is how it needs to be...

Hi Sadie - could you structure it like we do in cf-python, perhaps?

Hi Sadie - could you structure it like we do in cf-python, perhaps?

I could, but then I would have to go and change all of the links I've updated with bulid/ elsewhere (e.g. for the CF Conventions software page, etc.) for the sake of getting them updated quickly.

Having a separate build directory really helps me with general development, e.g. when you grep in the docs directory for the setup of e.g. the cf-python docs you have a mixture of HTML and RST directories and files and it is never clear what is a permanent codebase directory or a generated build directory in there to me from that, so I am not just being a pain (at least, not trying to be)! 😆

For now I think we have three options on this note:

1. I can put the merge of this on hold and I can expedite my plans to work out how to redirect to remove the build/ component from the URL even though that is where the built content will live, which isn't ideal in the link for sure (even though having it as a directory is useful as per above) so that we can get both https://ncas-cms.github.io/cf-plot/build/<subpaths> and https://ncas-cms.github.io/cf-plot/<same subpaths> working and I can use the latter links here (and in general, going forward).
2. You could allow this PR to go in as-is with the build/ in the URL, which we appreciate is not ideal but does work.
3. I could indeed change the structuring but then suffer from the issues I describe above for cf-plot and need to fix the links to remove the build/ elsewhere.

I prefer (1) since then I'll be getting something done I have been putting off and we will both be happy (I think?), what do you think?

I should add, it's a shame GitHub Pages doesn't let me serve the docs site from docs/build/ rather than just docs, which would solve the problem seamlessly, but from some investigation it does not, probably for good reason.

Oh wait! I have a new fourth option that is probably the best way forward:

4. I don't build the content locally and to the codebase, I use GitHub Actions to build and push it to a GitHub pages branch which is the one that gets hosted. I've seen this done with numerous other projects and it seems a really clean way to do the build. Though, that will break the links elsewhere.

In the interests of getting this fixed for the next release, I will merge this - but I have noted that I should ideally get the URL fr the cf-plot docs updated from https://ncas-cms.github.io/cf-plot/build/... to https://ncas-cms.github.io/cf-plot/... without the build endpoint to the URL, ideally without having to put the source and built content in the same directory, probably via setting up the docs building via a GitHub Actions job, as per my previous comments.